ODFocusModule

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODFocusModule

Superclasses
ODObject
Subclasses
none

An object of the ODFocusModule class is used to manage a particular type (or types) of focus or ownership of a shared resource.

Description
A focus is a designation of ownership of a given shared resource or feature, such as the keyboard or menu bar. A frame that owns an event-related focus receives events pertaining to that resource. A focus module manages a particular focus, maintaining the identity of the individual frame that owns the focus. The arbitrator uses at least one internal focus module to handle standard OpenDoc event types of a particular platform. Typically, you do not need to subclass ODFocusModule or even access the internal focus modules directly. However, you can define additional focus types, as needed, to handle other kinds of user events (such as input from new kinds of devices) by creating a new kind of focus module.
The ODFocusModule class is an abstract superclass that you can subclass to create a focus module. You can create a focus module object either from within a shell plug-in or from within one of your part's methods that are called during startup.
Before OpenDoc is able to recognize your new type of focus, you must register the associated focus module with the arbitrator. To register a focus module, you call the arbitrator's RegisterFocus method (page 50); to remove the focus module, call the arbitrator's UnregisterFocus method (page 58). For more information related to the arbitrator, see the ODArbitrator class description (page 43). For more information on creating custom focus types, see the chapter on extending OpenDoc in the OpenDoc Programmer's Guide for the MacOS.

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODFocusModule.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
If you subclass ODFocusModule, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this focus module object. The SOM library calls this method when this focus module is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in this focus module's subclass-specific initialization method; see also the InitFocusModule method (page 272).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
If you subclass ODFocusModule, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this focus module object, including any storage related to additional instance variables initialized in this focus module object. The SOM library calls this method when this focus module is deleted; this method must not fail.

Methods
This section presents summary descriptions of the ODFocusModule methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Initializing

InitFocusModule
Initializes this focus module object.
Transfer Focus

TransferFocusOwnership
Should transfer ownership of the specified focus from one frame to another frame.
BeginRelinquishFocus
Should return a Boolean value that indicates whether the current owner of the specified exclusive focus is willing to give up ownership of the focus.
CommitRelinquishFocus
Should signal to the part that owns the specified exclusive focus that it is about to lose ownership of it.
AbortRelinquishFocus
Should cancel the request for the frame to relinquish ownership of the specified exclusive focus.
Focus Ownership

CreateOwnerIterator
Should create a focus-owner iterator to give callers access to the frames that own the specified nonexclusive focus.
AcquireFocusOwner
Should return a reference to the frame that owns the specified exclusive focus.
SetFocusOwnership
Should record the specified frame as an owner of the specified focus.
UnsetFocusOwnership
Should remove the specified frame as an owner of the specified focus.
Focus Testing

IsFocusExclusive
Should return a Boolean value that indicates whether the specified focus is exclusive.

Methods
AbortRelinquishFocus
AcquireFocusOwner
BeginRelinquishFocus
CommitRelinquishFocus
CreateOwnerIterator
InitFocusModule
IsFocusExclusive
SetFocusOwnership
TransferFocusOwnership
UnsetFocusOwnership